<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 8.4</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="8.3.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="8.5.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P1">Part I. The Language</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#8">Chapter 8. Compilation, Execution, and Errors</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><h2>8.4 &ndash; Error Handling and Exceptions</h2>

<p>For many applications,
you do not need to do any error handling in Lua.
Usually, the application program does this handling.
All Lua activities start from a call by the application,
usually asking Lua to run a chunk.
If there is any error, this call returns an error code
and the application can take appropriate actions.
In the case of the stand-alone interpreter,
its main loop just prints the error message
and continues showing the prompt and running the commands.

<p>If you need to handle errors in Lua,
you should use the <code>pcall</code> function (<em>protected call</em>)
to encapsulate your code.

<p>Suppose you want to run a piece of Lua code
and to catch
any error raised while running that code.
Your first step is to encapsulate that piece of code in
a function; let us call it <code>foo</code>:
<pre>
    function foo ()
        ...
      if unexpected_condition then error() end
        ...
      print(a[i])    -- potential error: `a' may not be a table
        ...
    end
</pre>
Then, you call <code>foo</code> with <code>pcall</code>:
<pre>
    if pcall(foo) then
      -- no errors while running `foo'
      ...
    else
      -- `foo' raised an error: take appropriate actions
      ...
    end
</pre>
Of course, you can call <code>pcall</code> with an anonymous function:
<pre>
    if pcall(function () ... end) then ...
    else ...
</pre>

<p>The <code>pcall</code> function calls its first argument in
<em>protected mode</em>,
so that it catches any errors while the function is running.
If there are no errors,
<code>pcall</code> returns <B>true</B>, plus any values returned by the call.
Otherwise, it returns <B>false</B>, plus the error message.

<p>Despite its name, the error message does not have to be a string.
Any Lua value that you pass to <code>error</code> will be returned by <code>pcall</code>:
<pre>
    local status, err = pcall(function () error({code=121}) end)
    print(err.code)  -->  121
</pre>
These mechanisms provide all we need to do
exception handling in Lua.
We <em>throw</em> an exception with <code>error</code>
and <em>catch</em> it with <code>pcall</code>.
The error message identifies the kind or error.

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="8.5.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

